package com.br.cashflowdao.hibernate.dao;

import java.io.Serializable;
import java.util.List;

/**
 * This interface provides all the facilities to perform default CRUD operations.
 * <p>
 * Any method here defined is focused only in <b>default<b> CRUD operation, any
 * class implementing this interface that needs more advanced CRUD operations
 * are free to define and implement their own CRUD methods. Other interfaces are
 * also free to extend and define new CRUD methods as well.
 * <p>
 * Since any error related to CRUD operation are unrecoverable, the methods hereby
 * defined are meant to handle all those database and Hibernate specific exceptions
 * in the form of the default unchecked java <Exception>.
 * Besides that any programatic exception should never be omitted and must be throw explictly,
 * the API user is responsible to handle those exception.
 * <p>
 *
 * @param <code><T></code> entity used for CRUD purpose
 * @param <code><ID></code> entity's identifier
 * 
 * @author Marcel Sena <marcel.sena at marcel.sena@gmail.com>
 * @version 1.0
 * @since 05/01/2009
 */
public interface IDAO <T, ID extends Serializable> {

    /**
     * Finds a entity by its identifier.
     * <p>
     *
     * @param entity's unique identifier which will be used as
     * the only parameter to perform the querying operation.
     * @return an entity found using the specified arguments
     * or <code>null</code> if no data is found.
     * @throws an <code>Exception</code> if anything goes wrong when attempting
     * to retreive the entity.
     */
    @SuppressWarnings("unchecked")
    public T findById(ID id);

    /**
     * This method uses the given entity's properties as criteria for querying purpose.
     * <p>
     *
     * @param an entity used for querying purpose.
     * @param an array of <code>String</code> contaning all entity's properties
     * that will be excluded from the query criteria.
     * @return a list containing all entities found or <code>null</code>
     * if no data is found.
     * @throws an <code>Exception</code> if anything goes wrong when attempting to retreive the entities.
     * @throws an <code>NullPointerException</code> if the given array is <code>null</code>
     */
    @SuppressWarnings("unchecked")
    public List<T> findByExample(T entity, String[] excludeProperty);

    /**
     * Find all entities of the same type. 
     * <p>
     *
     * @return a list containing all the entities found or <code>null</code>
     * if no data is found.
     * @throws an <code>Exception</code> if anything goes wrong when attempting to retreive the entities.
     * @see #add(Object)
     */
    @SuppressWarnings("unchecked")
    public List<T> findAll();

    /**
     * Saves or Updates an entity's state.
     *
     * @param an entity to be persisted or updated.
     * @return an entity with its current state
     * @throws an <code>Exception</code> if anything goes wrong during the save
     * or update operation.
     */
    @SuppressWarnings("unchecked")
    public T createOrUpdate(T entity);

    /**
     * Removes the given entity.
     *
     * @param an entity that will be removed
     * @throws an <code>Exception</code> if anything goes wrong during the save
     * or update operation.
     */
    @SuppressWarnings("unchecked")
    public void remove(T entity);


}
